Summary

• Adds [python].lockfile_resolver = "uv" option (default: pex) for faster lockfile generation
• Uses uv pip compile to pre-resolve pinned requirements, then pex lock create --no-transitive to materialize the PEX lockfile
• Supports all lock styles including universal (via uv pip compile --universal)
• Adds [uv].args_for_lockfile_resolve for passthrough flags (e.g., --index-strategy unsafe-first-match)

Motivation

Issue: #20679 — faster, more ergonomic lockfile generation by leveraging uv's PubGrub resolver.

This builds on the uv PEX builder from #23197 (merged) and is inspired by the approach in #22949, with key improvements:

Benchmarks

Environment: Apple M4, macOS 15.x (Darwin 24.6.0), arm64
Dataset: 87 top-level requirements (Trio test deps + web/data/cloud ecosystem) → 169 resolved packages
Tool: hyperfine v1.20.0
Methodology: Same dataset structure as uv's own benchmarks (Trio project requirements)

Resolver-only comparison (no Pants overhead)

Isolates the dependency resolution step — uv pip compile vs pex lock create:

End-to-end Pants comparison

Full pants generate-lockfiles --resolve=... (includes engine init, interpreter discovery, PEX CLI bootstrap):

Note: End-to-end improvement is smaller because Pants engine overhead (~20s) is constant. The uv resolver also shows much lower variance (±0.8s vs ±13.7s), providing more consistent lockfile generation times.

Correctness

Both resolvers produce equivalent lockfiles — 168/169 packages identical, with minor differences in optional/conditional dependency selection (greenlet vs tomli), which is expected behavior between different resolvers.

Reproduction

# Direct resolver comparison (cold)
hyperfine --runs 3 \
  --prepare "rm -rf /tmp/pex-bench-cache /tmp/uv-bench-cache" \
  -n "pex lock create" \
    "PEX_ROOT=/tmp/pex-bench-cache pex3 lock create --style=universal --target-system linux --target-system mac --interpreter-constraint 'CPython==3.11.*' --output=/tmp/out.json -r requirements.txt" \
  -n "uv pip compile" \
    "UV_CACHE_DIR=/tmp/uv-bench-cache uv pip compile requirements.txt --output-file /tmp/out.txt --python-version 3.11 --no-header --no-annotate"

# End-to-end Pants comparison (from pants source checkout with this PR)
hyperfine --runs 3 \
  --prepare "rm -rf ~/.cache/pants/lmdb_store && rm -f path/to/lockfile" \
  -n "pex" "./pants --no-pantsd --python-lockfile-resolver=pex generate-lockfiles --resolve=..." \
  -n "uv"  "./pants --no-pantsd --python-lockfile-resolver=uv generate-lockfiles --resolve=..."

Disclaimers

• Results are environment-specific; performance varies by hardware, OS, and network
• "Cold" clears process/resolver caches; "semi-warm" retains downloaded wheel caches to isolate resolver speed from network I/O
• --no-pantsd used for all measurements (no daemon memoization)
• The end-to-end Pants test runs from source (includes Rust engine compilation overhead not present in released binaries)

How it works

requirements (from targets)
        │
        │  [python].lockfile_resolver = "uv"
        ▼
  uv pip compile [--universal] [--python-version X.Y]
        │
        ▼
  pinned requirements.txt
        │
        │  pex lock create --no-transitive --style={universal,strict,sources}
        ▼
  PEX lockfile (same format as today)

Usage

[python]
enable_resolves = true
lockfile_resolver = "uv"  # opt-in

[uv]
args_for_lockfile_resolve = ["--index-strategy", "unsafe-first-match"]

Current limitations

Code changes

Test plan

• test_strip_named_repo — unit test for index URL stripping helper
• test_uv_resolver_rejects_complete_platforms — validates error on unsupported complete_platforms
• test_uv_resolver_strict_requires_single_python — validates error on multi-version strict
• test_uv_resolver_rejects_overrides — validates error on unsupported overrides
• test_uv_resolver_strict_generates_valid_lockfile — E2E: generates valid PEX lockfile with uv + strict
• test_uv_resolver_universal_generates_valid_lockfile — E2E: generates valid PEX lockfile with uv + universal
• All existing lockfile tests pass unchanged

AI disclosure

This PR was created with extensive use of Claude Code (Anthropic's CLI agent). Claude explored the Pants codebase, designed the implementation approach, wrote the code/tests/docs, and ran the benchmarks. All changes were reviewed and test runs verified by the author.

🤖 Generated with Claude Code